docs(android): Introduce Android ProfilingManager options by markushi · Pull Request #18481 · getsentry/sentry-docs

markushi · 2026-06-18T21:57:05Z

DESCRIBE YOUR PR

Introduce new docs for Android ProfilingManager.

Warning

do not merge before getsentry/sentry-java#5251

IS YOUR CHANGE URGENT?

Help us prioritize incoming PRs by letting us know when the change needs to go live.

Urgent deadline (GA date, etc.):
Other deadline:
None: Not urgent, can wait up to 1 week+

SLA

Teamwork makes the dream work, so please add a reviewer to your PRs.
Please give the docs team up to 1 week to review your PR unless you've added an urgent due date to it.
Thanks in advance for your help!

PRE-MERGE CHECKLIST

Make sure you've checked the following before merging your changes:

Checked Vercel preview for correctness, including links
PR was reviewed and approved by any necessary SMEs (subject matter experts)
PR was reviewed and approved by a member of the Sentry docs team
feat(profiling): Add Android ProfilingManager (Perfetto) support sentry-java#5251 was merged
Correct min-sdk version is used
continuous-profiling-perfetto feature flag was rolled out for both relay

vercel · 2026-06-18T21:57:11Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
sentry-docs	Ready	Preview, Comment	Jun 19, 2026 6:13am

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
develop-docs	Ignored	Preview	Jun 19, 2026 6:13am

UI Profiling relies on the Android ProfilingManager, which rate limits profiling requests at the framework level on top of the SDK sampling rate. Document this in the Limitations section and add a callout with the shell command to disable the restrictions for local testing. Co-Authored-By: Claude <noreply@anthropic.com>

coolguyzone · 2026-06-23T20:48:30Z


+<SdkOption name="useProfilingManager" type="bool" defaultValue="false" availableSince="8.45.0">
+
+When `true`, UI Profiling uses the Android <Link to="https://developer.android.com/reference/android/os/ProfilingManager">ProfilingManager</Link> to capture <Link to="https://perfetto.dev/">Perfetto</Link> traces. This is the recommended backend and requires Android 15 (API level 35) or higher. On older devices, profiling won't run and there is no fallback to the legacy profiler. When `false`, the SDK uses the <PlatformLink to="/profiling/legacy">legacy `tracer` backend</PlatformLink>.


Suggested change

When `true`, UI Profiling uses the Android <Link to="https://developer.android.com/reference/android/os/ProfilingManager">ProfilingManager</Link> to capture <Link to="https://perfetto.dev/">Perfetto</Link> traces. This is the recommended backend and requires Android 15 (API level 35) or higher. On older devices, profiling won't run and there is no fallback to the legacy profiler. When `false`, the SDK uses the <PlatformLink to="/profiling/legacy">legacy `tracer` backend</PlatformLink>.

When `true`, UI Profiling uses the Android <Link to="https://developer.android.com/reference/android/os/ProfilingManager">ProfilingManager</Link> to capture <Link to="https://perfetto.dev/">Perfetto</Link> traces. This is the preferred profiling implementation and requires Android 15 (API level 35) or higher. On older devices, profiling won't run and there is no fallback to the legacy profiler. When `false`, the SDK uses the <PlatformLink to="/profiling/legacy">legacy `tracer` backend</PlatformLink>.

coolguyzone · 2026-06-23T20:51:56Z

+---
+title: Legacy Profiling
+sidebar_title: Legacy Profiling
+description: "Learn about the legacy profiling implementations and how to use them on devices below Android 15."


Suggested change

description: "Learn about the legacy profiling implementations and how to use them on devices below Android 15."

description: "Learn about the legacy profilers and how to use them on devices running Android versions earlier than Android 15."

coolguyzone · 2026-06-23T20:55:36Z

+
+<Alert level="warning" title="Legacy">
+  This page documents Sentry's legacy Android profilers. The recommended way to
+  profile your app is the{" "}


Suggested change

profile your app is the{" "}

profile your app is the is the <PlatformLink to="/profiling/">ProfilingManager (Perfetto) based UI Profiling</PlatformLink>, available since SDK version `8.45.0`. Use the legacy profilers only when you need to support devices running below Android 15 (API level 35), or while migrating from an older setup.

Putting this all on one line to fix a formatting issue.

coolguyzone · 2026-06-23T20:55:50Z

+<Alert level="warning" title="Legacy">
+  This page documents Sentry's legacy Android profilers. The recommended way to
+  profile your app is the{" "}
+  <PlatformLink to="/profiling/">


Suggested change

<PlatformLink to="/profiling/">

coolguyzone · 2026-06-23T20:56:05Z

+  This page documents Sentry's legacy Android profilers. The recommended way to
+  profile your app is the{" "}
+  <PlatformLink to="/profiling/">
+    ProfilingManager (Perfetto) based UI Profiling


Suggested change

ProfilingManager (Perfetto) based UI Profiling

coolguyzone · 2026-06-23T20:56:16Z

+  profile your app is the{" "}
+  <PlatformLink to="/profiling/">
+    ProfilingManager (Perfetto) based UI Profiling
+  </PlatformLink>


Suggested change

</PlatformLink>

coolguyzone · 2026-06-23T20:56:26Z

+  </PlatformLink>
+  , available since SDK version `8.45.0`. Use the legacy profilers only when you


Suggested change

</PlatformLink>

, available since SDK version `8.45.0`. Use the legacy profilers only when you

coolguyzone · 2026-06-23T20:56:35Z

+    ProfilingManager (Perfetto) based UI Profiling
+  </PlatformLink>
+  , available since SDK version `8.45.0`. Use the legacy profilers only when you
+  need to support devices running below Android 15 (API level 35), or while


Suggested change

need to support devices running below Android 15 (API level 35), or while

coolguyzone · 2026-06-23T20:56:45Z

+  </PlatformLink>
+  , available since SDK version `8.45.0`. Use the legacy profilers only when you
+  need to support devices running below Android 15 (API level 35), or while
+  migrating from an older setup.


Suggested change

migrating from an older setup.

coolguyzone · 2026-06-23T21:05:38Z

+<Alert level="warning" title="Important">
+  Legacy UI Profiling and transaction-based profiling use the Android runtime's
+  `tracer` under the hood to sample threads. There are known issues that this
+  `tracer` can cause crashes in certain circumstances. See this{" "}


Suggested change

`tracer` can cause crashes in certain circumstances. See this{" "}

`tracer` can cause crashes in certain circumstances. See this <PlatformLink to="/profiling/troubleshooting#i-see-an-elevated-number-of-crashes-in-the-android-runtime-when-profiling-is-activated"> troubleshooting </PlatformLink> entry for more information. The ProfilingManager (Perfetto) based <PlatformLink to="/profiling/">UI Profiling</PlatformLink> is not affected by these issues.

coolguyzone · 2026-06-23T21:05:51Z

+  Legacy UI Profiling and transaction-based profiling use the Android runtime's
+  `tracer` under the hood to sample threads. There are known issues that this
+  `tracer` can cause crashes in certain circumstances. See this{" "}
+  <PlatformLink to="/profiling/troubleshooting#i-see-an-elevated-number-of-crashes-in-the-android-runtime-when-profiling-is-activated">


Suggested change

<PlatformLink to="/profiling/troubleshooting#i-see-an-elevated-number-of-crashes-in-the-android-runtime-when-profiling-is-activated">

coolguyzone · 2026-06-23T21:06:04Z

+  `tracer` under the hood to sample threads. There are known issues that this
+  `tracer` can cause crashes in certain circumstances. See this{" "}
+  <PlatformLink to="/profiling/troubleshooting#i-see-an-elevated-number-of-crashes-in-the-android-runtime-when-profiling-is-activated">
+    troubleshooting


Suggested change

troubleshooting

coolguyzone · 2026-06-23T21:06:11Z

+  `tracer` can cause crashes in certain circumstances. See this{" "}
+  <PlatformLink to="/profiling/troubleshooting#i-see-an-elevated-number-of-crashes-in-the-android-runtime-when-profiling-is-activated">
+    troubleshooting
+  </PlatformLink>{" "}


Suggested change

</PlatformLink>{" "}

coolguyzone · 2026-06-23T21:06:22Z

+  <PlatformLink to="/profiling/troubleshooting#i-see-an-elevated-number-of-crashes-in-the-android-runtime-when-profiling-is-activated">
+    troubleshooting
+  </PlatformLink>{" "}
+  entry for more information. The ProfilingManager (Perfetto) based{" "}


Suggested change

entry for more information. The ProfilingManager (Perfetto) based{" "}

coolguyzone · 2026-06-23T21:06:29Z

+    troubleshooting
+  </PlatformLink>{" "}
+  entry for more information. The ProfilingManager (Perfetto) based{" "}
+  <PlatformLink to="/profiling/">UI Profiling</PlatformLink> is not affected by


Suggested change

<PlatformLink to="/profiling/">UI Profiling</PlatformLink> is not affected by

coolguyzone · 2026-06-23T21:06:39Z

+  </PlatformLink>{" "}
+  entry for more information. The ProfilingManager (Perfetto) based{" "}
+  <PlatformLink to="/profiling/">UI Profiling</PlatformLink> is not affected by
+  these issues.


Suggested change

these issues.

coolguyzone · 2026-06-23T21:07:05Z

+
+## Legacy UI Profiling
+
+Legacy UI Profiling is available starting in SDK version `8.7.0` and is supported on API level 21 and up.


Suggested change

Legacy UI Profiling is available starting in SDK version `8.7.0` and is supported on API level 21 and up.

Legacy UI Profiling is available starting with SDK version `8.7.0` and is supported on API level 21 and up.

coolguyzone · 2026-06-23T21:08:42Z

+
+<Alert>
+
+This is the oldest profiling implementation and will eventually be deprecated. We recommend upgrading to the <PlatformLink to="/profiling/">ProfilingManager (Perfetto) based UI Profiling</PlatformLink>. The same behaviour, without the 30 seconds limitation, can be achieved with the trace lifecycle. In order to upgrade, you also need to remove the <PlatformLink to="/configuration/options/#transaction-based-profiling-options">transaction-based profiling options</PlatformLink> from your configuration.


Suggested change

This is the oldest profiling implementation and will eventually be deprecated. We recommend upgrading to the <PlatformLink to="/profiling/">ProfilingManager (Perfetto) based UI Profiling</PlatformLink>. The same behaviour, without the 30 seconds limitation, can be achieved with the trace lifecycle. In order to upgrade, you also need to remove the <PlatformLink to="/configuration/options/#transaction-based-profiling-options">transaction-based profiling options</PlatformLink> from your configuration.

This is the oldest profiling implementation and will eventually be deprecated. We recommend upgrading to the <PlatformLink to="/profiling/">ProfilingManager (Perfetto) based UI Profiling</PlatformLink>. The same behavior, without the 30 seconds limitation, can be achieved with the trace lifecycle. In order to upgrade, you also need to remove the <PlatformLink to="/configuration/options/#transaction-based-profiling-options">transaction-based profiling options</PlatformLink> from your configuration.

coolguyzone · 2026-06-23T21:10:14Z

-<Alert level="info" title="Improved Profiling Coming Soon">
-  We're working on a more stable profiling solution based on the Android <Link to="https://developer.android.com/reference/android/os/ProfilingManager">ProfilingManager APIs (Perfetto)</Link>. Follow the <Link to="https://github.com/getsentry/sentry-java/discussions/5560">discussion on GitHub</Link> for updates.
+<Alert level="info" title="Using the recommended profiler?">
+  The crash-related issues below only affect{" "}


Suggested change

The crash-related issues below only affect{" "}

The crash-related issues below only affect <PlatformLink to="/profiling/legacy">Legacy Profiling</PlatformLink>, which uses the Android runtime's `tracer`. The recommended <PlatformLink to="/profiling/"> ProfilingManager (Perfetto) based UI Profiling </PlatformLink> is not affected.

coolguyzone · 2026-06-23T21:10:31Z

-  We're working on a more stable profiling solution based on the Android <Link to="https://developer.android.com/reference/android/os/ProfilingManager">ProfilingManager APIs (Perfetto)</Link>. Follow the <Link to="https://github.com/getsentry/sentry-java/discussions/5560">discussion on GitHub</Link> for updates.
+<Alert level="info" title="Using the recommended profiler?">
+  The crash-related issues below only affect{" "}
+  <PlatformLink to="/profiling/legacy">Legacy Profiling</PlatformLink>, which


Suggested change

<PlatformLink to="/profiling/legacy">Legacy Profiling</PlatformLink>, which

coolguyzone · 2026-06-23T21:10:38Z

+<Alert level="info" title="Using the recommended profiler?">
+  The crash-related issues below only affect{" "}
+  <PlatformLink to="/profiling/legacy">Legacy Profiling</PlatformLink>, which
+  uses the Android runtime's `tracer`. The recommended{" "}


Suggested change

uses the Android runtime's `tracer`. The recommended{" "}

coolguyzone · 2026-06-23T21:10:44Z

+  The crash-related issues below only affect{" "}
+  <PlatformLink to="/profiling/legacy">Legacy Profiling</PlatformLink>, which
+  uses the Android runtime's `tracer`. The recommended{" "}
+  <PlatformLink to="/profiling/">


Suggested change

<PlatformLink to="/profiling/">

coolguyzone · 2026-06-23T21:10:55Z

+  <PlatformLink to="/profiling/legacy">Legacy Profiling</PlatformLink>, which
+  uses the Android runtime's `tracer`. The recommended{" "}
+  <PlatformLink to="/profiling/">
+    ProfilingManager (Perfetto) based UI Profiling


Suggested change

ProfilingManager (Perfetto) based UI Profiling

coolguyzone · 2026-06-23T21:11:00Z

+  uses the Android runtime's `tracer`. The recommended{" "}
+  <PlatformLink to="/profiling/">
+    ProfilingManager (Perfetto) based UI Profiling
+  </PlatformLink>{" "}


Suggested change

</PlatformLink>{" "}

coolguyzone · 2026-06-23T21:11:08Z

+  <PlatformLink to="/profiling/">
+    ProfilingManager (Perfetto) based UI Profiling
+  </PlatformLink>{" "}
+  is not affected.


Suggested change

is not affected.

coolguyzone · 2026-06-23T21:12:11Z

 ## I see an elevated number of crashes in the Android Runtime when profiling is activated

-Profiling uses the Android runtime's `tracer` under the hood to sample threads. There are known issues that this `tracer` can cause crashes in certain circumstances. Read on for more information, and subscribe to this <Link to="https://github.com/getsentry/sentry-java/issues/3679">GitHub issue</Link> for updates.
+<PlatformLink to="/profiling/legacy">Legacy Profiling</PlatformLink> uses the


Please follow my examples above and put this in-line to fix the extra line breaks that are appearing here.

coolguyzone · 2026-06-23T21:15:43Z

-<Alert level="warning">
-  Profiling uses the Android runtime's `tracer` under the hood to sample threads. There are known issues that this `tracer` can cause crashes in certain circumstances. See this <PlatformLink to="/profiling/troubleshooting#i-see-an-elevated-number-of-crashes-in-the-android-runtime-when-profiling-is-activated">troubleshooting</PlatformLink> entry for more information.
+<Alert level="info">
+  Profiling uses the Android{" "}


Another section that needs to be in-lined.

coolguyzone

Some of the formatting needs adjusting, but once those are done this looks good to go!

docs(android): Introduce Android ProfilingManager options

e7bb0fa

codeowner-assignment Bot requested a review from a team June 18, 2026 21:57

vercel Bot deployed to Preview – sentry-docs June 18, 2026 22:02 View deployment

vercel Bot deployed to Preview – sentry-docs June 19, 2026 06:13 View deployment

coolguyzone reviewed Jun 23, 2026

View reviewed changes

coolguyzone approved these changes Jun 23, 2026

View reviewed changes


		<SdkOption name="useProfilingManager" type="bool" defaultValue="false" availableSince="8.45.0">

		When `true`, UI Profiling uses the Android <Link to="https://developer.android.com/reference/android/os/ProfilingManager">ProfilingManager</Link> to capture <Link to="https://perfetto.dev/">Perfetto</Link> traces. This is the recommended backend and requires Android 15 (API level 35) or higher. On older devices, profiling won't run and there is no fallback to the legacy profiler. When `false`, the SDK uses the <PlatformLink to="/profiling/legacy">legacy `tracer` backend</PlatformLink>.

	description: "Learn about the legacy profiling implementations and how to use them on devices below Android 15."
	description: "Learn about the legacy profilers and how to use them on devices running Android versions earlier than Android 15."

	profile your app is the{" "}
	profile your app is the is the <PlatformLink to="/profiling/">ProfilingManager (Perfetto) based UI Profiling</PlatformLink>, available since SDK version `8.45.0`. Use the legacy profilers only when you need to support devices running below Android 15 (API level 35), or while migrating from an older setup.

		</PlatformLink>
		, available since SDK version `8.45.0`. Use the legacy profilers only when you

	`tracer` can cause crashes in certain circumstances. See this{" "}
	`tracer` can cause crashes in certain circumstances. See this <PlatformLink to="/profiling/troubleshooting#i-see-an-elevated-number-of-crashes-in-the-android-runtime-when-profiling-is-activated"> troubleshooting </PlatformLink> entry for more information. The ProfilingManager (Perfetto) based <PlatformLink to="/profiling/">UI Profiling</PlatformLink> is not affected by these issues.


		## Legacy UI Profiling

		Legacy UI Profiling is available starting in SDK version `8.7.0` and is supported on API level 21 and up.


		<Alert>

		This is the oldest profiling implementation and will eventually be deprecated. We recommend upgrading to the <PlatformLink to="/profiling/">ProfilingManager (Perfetto) based UI Profiling</PlatformLink>. The same behaviour, without the 30 seconds limitation, can be achieved with the trace lifecycle. In order to upgrade, you also need to remove the <PlatformLink to="/configuration/options/#transaction-based-profiling-options">transaction-based profiling options</PlatformLink> from your configuration.

	The crash-related issues below only affect{" "}
	The crash-related issues below only affect <PlatformLink to="/profiling/legacy">Legacy Profiling</PlatformLink>, which uses the Android runtime's `tracer`. The recommended <PlatformLink to="/profiling/"> ProfilingManager (Perfetto) based UI Profiling </PlatformLink> is not affected.

Uh oh!

Conversation

markushi commented Jun 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

DESCRIBE YOUR PR

IS YOUR CHANGE URGENT?

SLA

PRE-MERGE CHECKLIST

Uh oh!

vercel Bot commented Jun 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

coolguyzone Jun 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

coolguyzone left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

markushi commented Jun 18, 2026 •

edited

Loading

vercel Bot commented Jun 18, 2026 •

edited

Loading

coolguyzone Jun 23, 2026 •

edited

Loading